//+------------------------------------------------------------------+
//|                                              CompareFunction.mqh |
//|                             Copyright 2000-2025, MetaQuotes Ltd. |
//|                                             https://www.mql5.com |
//+------------------------------------------------------------------+
#include <Generic/Interfaces/IComparable.h>  // 可比较接口（支撑自定义类型的比较逻辑）

//+------------------------------------------------------------------+
//| 布尔值比较函数：比较两个 bool 类型值的大小关系                     |
//| 比较规则（布尔值的自然排序）：false < true                        |
//| 返回值说明：                                                     |
//|  - 1：x > y（x=true 且 y=false）                                  |
//|  - -1：x < y（x=false 且 y=true）                                 |
//|  - 0：x == y（x与y均为true 或 均为false）                        |
//| 适用场景：布尔值排序（如按“是否启用”筛选后的配置项排序）、条件判断中的优先级比较 |
//+------------------------------------------------------------------+
int Compare(
    const bool x,  // [in] 待比较的第一个布尔值
    const bool y   // [in] 待比较的第二个布尔值
);

//+------------------------------------------------------------------+
//| 有符号字符比较函数：比较两个 char 类型值的大小关系（基于 ASCII 码值） |
//| 比较规则（ASCII 码序）：字符的 ASCII 码值越大，该字符“越大”          |
//| 返回值说明：                                                     |
//|  - 1：x 的 ASCII 码值 > y 的 ASCII 码值                          |
//|  - -1：x 的 ASCII 码值 < y 的 ASCII 码值                         |
//|  - 0：x 的 ASCII 码值 == y 的 ASCII 码值                        |
//| 适用场景：字符排序（如字母表顺序排列）、ASCII 码相关的逻辑判断（如符号/数字区分） |
//+------------------------------------------------------------------+
int Compare(
    const char x,  // [in] 待比较的第一个有符号字符（ASCII 码范围：-128 ~ 127）
    const char y   // [in] 待比较的第二个有符号字符
);

//+------------------------------------------------------------------+
//| 无符号字符比较函数：比较两个 uchar 类型值的大小关系（基于 ASCII 码值） |
//| 比较规则（无符号数值序）：字符的 ASCII 码值（无符号）越大，该字符“越大”  |
//| 返回值说明：                                                     |
//|  - 1：x 的 ASCII 码值（无符号）> y 的 ASCII 码值                  |
//|  - -1：x 的 ASCII 码值（无符号）< y 的 ASCII 码值                 |
//|  - 0：x 的 ASCII 码值（无符号）== y 的 ASCII 码值                |
//| 适用场景：无符号字符处理（如字节流数据排序、图像像素值比较）、ASCII 码全范围（0~255）比较 |
//+------------------------------------------------------------------+
int Compare(
    const uchar x,  // [in] 待比较的第一个无符号字符（ASCII 码范围：0 ~ 255）
    const uchar y   // [in] 待比较的第二个无符号字符
);

//+------------------------------------------------------------------+
//| 短整型比较函数：比较两个 short 类型值的大小关系（有符号整数序）      |
//| 比较规则（有符号数值序）：按数学整数大小比较，支持负数（负数值 < 非负数值） |
//| 返回值说明：                                                     |
//|  - 1：x（数学值）> y（数学值）                                   |
//|  - -1：x（数学值）< y（数学值）                                  |
//|  - 0：x（数学值）== y（数学值）                                 |
//| 适用场景：短整型数据排序（如小范围计数数据、16位传感器数值）、内存敏感场景的整数比较 |
//+------------------------------------------------------------------+
int Compare(
    const short x,  // [in] 待比较的第一个短整型（范围：-32768 ~ 32767）
    const short y   // [in] 待比较的第二个短整型
);

//+------------------------------------------------------------------+
//| 无符号短整型比较函数：比较两个 ushort 类型值的大小关系（无符号整数序） |
//| 比较规则（无符号数值序）：按数学非负整数大小比较（仅支持 0 及正数）      |
//| 返回值说明：                                                     |
//|  - 1：x（数学值）> y（数学值）                                   |
//|  - -1：x（数学值）< y（数学值）                                  |
//|  - 0：x（数学值）== y（数学值）                                 |
//| 适用场景：无符号短整型数据处理（如16位ID、内存地址片段、非负计数数据） |
//+------------------------------------------------------------------+
int Compare(
    const ushort x,  // [in] 待比较的第一个无符号短整型（范围：0 ~ 65535）
    const ushort y   // [in] 待比较的第二个无符号短整型
);

//+------------------------------------------------------------------+
//| 颜色值比较函数：比较两个 color 类型值的大小关系（基于 RGB 编码值）    |
//| 比较规则（数值序）：color 本质为 32 位整数（ARGB 编码），按整数大小比较 |
//| 返回值说明：                                                     |
//|  - 1：x 的 ARGB 编码值 > y 的 ARGB 编码值                        |
//|  - -1：x 的 ARGB 编码值 < y 的 ARGB 编码值                       |
//|  - 0：x 的 ARGB 编码值 == y 的 ARGB 编码值                      |
//| 适用场景：颜色排序（如按亮度/饱和度间接排序，因 ARGB 数值与视觉属性无直接线性关系，需谨慎使用）、颜色列表去重 |
//+------------------------------------------------------------------+
int Compare(
    const color x,  // [in] 待比较的第一个颜色值（如 clrRed、RGB(255,0,0)）
    const color y   // [in] 待比较的第二个颜色值
);

//+------------------------------------------------------------------+
//| 整型比较函数：比较两个 int 类型值的大小关系（有符号整数序）          |
//| 比较规则（有符号数值序）：按数学整数大小比较，支持负数（负数值 < 非负数值） |
//| 返回值说明：                                                     |
//|  - 1：x（数学值）> y（数学值）                                   |
//|  - -1：x（数学值）< y（数学值）                                  |
//|  - 0：x（数学值）== y（数学值）                                 |
//| 适用场景：通用整型数据排序（如计数、ID、索引、时间戳片段）、大多数整数比较场景（MQL5 中最常用的整数类型） |
//+------------------------------------------------------------------+
int Compare(
    const int x,  // [in] 待比较的第一个整型（范围：-2147483648 ~ 2147483647）
    const int y   // [in] 待比较的第二个整型
);

//+------------------------------------------------------------------+
//| 无符号整型比较函数：比较两个 uint 类型值的大小关系（无符号整数序）     |
//| 比较规则（无符号数值序）：按数学非负整数大小比较（仅支持 0 及正数）      |
//| 返回值说明：                                                     |
//|  - 1：x（数学值）> y（数学值）                                   |
//|  - -1：x（数学值）< y（数学值）                                  |
//|  - 0：x（数学值）== y（数学值）                                 |
//| 适用场景：无符号整型数据处理（如32位ID、内存大小、哈希值、非负计数数据） |
//+------------------------------------------------------------------+
int Compare(
    const uint x,  // [in] 待比较的第一个无符号整型（范围：0 ~ 4294967295）
    const uint y   // [in] 待比较的第二个无符号整型
);

//+------------------------------------------------------------------+
//| 日期时间比较函数：比较两个 datetime 类型值的大小关系（时间序）        |
//| 比较规则（时间先后序）：datetime 本质为“从1970-01-01 00:00:00 开始的秒数”，数值越大表示时间越晚 |
//| 返回值说明：                                                     |
//|  - 1：x 代表的时间 > y 代表的时间（x 更晚）                      |
//|  - -1：x 代表的时间 < y 代表的时间（x 更早）                     |
//|  - 0：x 代表的时间 == y 代表的时间（同一时刻）                  |
//| 适用场景：时间排序（如日志时间、订单创建时间、数据采集时间）、时间范围判断（如“是否在有效期内”） |
//+------------------------------------------------------------------+
int Compare(
    const datetime x,  // [in] 待比较的第一个日期时间（如 D'2024.01.01'、TimeCurrent()）
    const datetime y   // [in] 待比较的第二个日期时间
);

//+------------------------------------------------------------------+
//| 长整型比较函数：比较两个 long 类型值的大小关系（有符号整数序）        |
//| 比较规则（有符号数值序）：按数学整数大小比较，支持大范围负数（负数值 < 非负数值） |
//| 返回值说明：                                                     |
//|  - 1：x（数学值）> y（数学值）                                   |
//|  - -1：x（数学值）< y（数学值）                                  |
//|  - 0：x（数学值）== y（数学值）                                 |
//| 适用场景：大范围整型数据处理（如64位ID、高精度计数、时间戳（毫秒/微秒级））、超出 int 范围的整数比较 |
//+------------------------------------------------------------------+
int Compare(
    const long x,  // [in] 待比较的第一个长整型（范围：-9223372036854775808 ~ 9223372036854775807）
    const long y   // [in] 待比较的第二个长整型
);

//+------------------------------------------------------------------+
//| 无符号长整型比较函数：比较两个 ulong 类型值的大小关系（无符号整数序）   |
//| 比较规则（无符号数值序）：按数学非负整数大小比较（支持超大范围非负数值）  |
//| 返回值说明：                                                     |
//|  - 1：x（数学值）> y（数学值）                                   |
//|  - -1：x（数学值）< y（数学值）                                  |
//|  - 0：x（数学值）== y（数学值）                                 |
//| 适用场景：超大范围无符号数据处理（如64位哈希值、唯一标识符（UUID）、磁盘容量） |
//+------------------------------------------------------------------+
int Compare(
    const ulong x,  // [in] 待比较的第一个无符号长整型（范围：0 ~ 18446744073709551615）
    const ulong y   // [in] 待比较的第二个无符号长整型
);

//+------------------------------------------------------------------+
//| 单精度浮点数比较函数：比较两个 float 类型值的大小关系（浮点数值序）    |
//| 比较规则（浮点数值序）：按数学实数大小比较，支持正负小数、零、无穷大（需注意精度问题） |
//| 注意事项：                                                       |
//|  1. 浮点精度限制：float 有效数字约 6~7 位，相近值（如 0.1f 与 0.1000001f）可能被误判为相等； |
//|  2. 特殊值处理：无穷大（INFINITY）> 任何有限值，NaN（非数值）与任何值比较结果均为 0； |
//| 返回值说明：                                                     |
//|  - 1：x（数学值）> y（数学值）（排除精度误差与特殊值场景）        |
//|  - -1：x（数学值）< y（数学值）（排除精度误差与特殊值场景）       |
//|  - 0：x（数学值）≈ y（数学值）或存在特殊值（NaN）                |
//| 适用场景：低精度浮点数据处理（如粗略的物理量、图形坐标）、内存敏感场景的浮点数比较 |
//+------------------------------------------------------------------+
int Compare(
    const float x,  // [in] 待比较的第一个单精度浮点数（范围：±1.175494351e-38 ~ ±3.402823466e+38）
    const float y   // [in] 待比较的第二个单精度浮点数
);

//+------------------------------------------------------------------+
//| 双精度浮点数比较函数：比较两个 double 类型值的大小关系（浮点数值序）    |
//| 比较规则（浮点数值序）：按数学实数大小比较，支持正负小数、零、无穷大（精度高于 float） |
//| 注意事项：                                                       |
//|  1. 浮点精度限制：double 有效数字约 15~17 位，仍需避免直接比较“相等”（建议用误差范围判断，如 |x-y| < 1e-9）； |
//|  2. 特殊值处理：无穷大（INFINITY）> 任何有限值，NaN（非数值）与任何值比较结果均为 0； |
//| 返回值说明：                                                     |
//|  - 1：x（数学值）> y（数学值）（排除精度误差与特殊值场景）        |
//|  - -1：x（数学值）< y（数学值）（排除精度误差与特殊值场景）       |
//|  - 0：x（数学值）≈ y（数学值）或存在特殊值（NaN）                |
//| 适用场景：高精度浮点数据处理（如金融价格、科学计算、高精度传感器数据）、MQL5 中最常用的浮点数比较场景 |
//+------------------------------------------------------------------+
int Compare(
    const double x,  // [in] 待比较的第一个双精度浮点数（范围：±2.2250738585072014e-308 ~ ±1.7976931348623157e+308）
    const double y   // [in] 待比较的第二个双精度浮点数
);

//+------------------------------------------------------------------+
//| 字符串比较函数：比较两个 string 类型值的大小关系（字典序/Unicode 码序） |
//| 比较规则（MQL5 字符串序）：基于字符的 Unicode 编码值，按“逐字符对比”逻辑，直至找到不同字符或字符串结束 |
//| 具体逻辑：                                                       |
//|  1. 逐字符比较 Unicode 码值，第一个不同字符的码值决定字符串大小；     |
//|  2. 若一个字符串是另一个的前缀（如 "abc" 与 "abcd"），则较短字符串“更小”； |
//|  3. 区分大小写（如 'A'（Unicode 65）< 'a'（Unicode 97），故 "Apple" < "apple"）； |
//| 返回值说明：                                                     |
//|  - 1：x 的字典序 > y 的字典序（如 "banana" > "apple"，"a1" > "a0"）  |
//|  - -1：x 的字典序 < y 的字典序（如 "apple" < "banana"，"a0" < "a1"） |
//|  - 0：x 与 y 完全相等（字符序列、长度均相同）                    |
//| 适用场景：字符串排序（如名称、关键词、ID 字符串）、字典/索引表查询、字符串去重 |
//+------------------------------------------------------------------+
int Compare(
    const string x,  // [in] 待比较的第一个字符串（如 "Hello"、StringConcatenate("a", "b")）
    const string y   // [in] 待比较的第二个字符串
);

//+------------------------------------------------------------------+
//| 泛型比较函数（模板）：比较两个自定义类型（实现 IComparable<T> 接口）的大小关系 |
//| 核心逻辑：                                                       |
//|  1. 尝试将第一个参数 x 转换为 IComparable<T> 接口实例（自定义类型需实现该接口）； |
//|  2. 若转换成功，调用接口的 Compare 方法（由自定义类型实现具体比较逻辑）； |
//|  3. 若转换失败（未实现 IComparable<T>），返回 0（表示“无法比较”）；    |
//| 返回值说明：                                                     |
//|  - 非 0 值：由自定义类型的 IComparable<T>::Compare 方法定义（通常 1 表示 x>y，-1 表示 x<y）； |
//|  - 0：无法比较（x 未实现 IComparable<T>）或 x == y（由自定义逻辑定义）； |
//| 适用场景：自定义类型的比较（如自定义订单类、用户类，需通过实现 IComparable<T> 接口定义比较规则） |
//| 使用要求：                                                       |
//|  自定义类型 T 必须实现 IComparable<T> 接口，并重写 Compare 方法，否则仅返回 0； |
//| 示例：                                                           |
//|  class COrder : public IComparable<COrder> {                     |
//|      double m_price;                                             |
//|      int Compare(COrder other) override {                        |
//|          return ::Compare(m_price, other.m_price); // 按价格比较订单 |
//|      }                                                           |
//|  };                                                              |
//+------------------------------------------------------------------+
template<typename T>
int Compare(
    T x,  // [in] 待比较的第一个自定义类型实例（需实现 IComparable<T> 接口）
    T y   // [in] 待比较的第二个自定义类型实例
);
//+------------------------------------------------------------------+